/**
 * Copyright (c) 2010 Simple Graph Tools contributors. All rights reserved.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * $Id$
 */
package org.sgt.transformations.graph2testdef;

import java.util.Map;
import java.util.Set;

import org.eclipse.emf.common.util.EList;
import org.sgt.coredef.Condition;
import org.sgt.coredef.Constraint;
import org.sgt.coredef.Graph;
import org.sgt.coredef.Node;
import org.sgt.coredef.util.Route;
import org.sgt.testdef.Step;
import org.sgt.testdef.TestCase;
import org.sgt.testdef.TestCondition;
import org.sgt.testdef.TestConstraint;
import org.sgt.testdef.TestPlan;
import org.sgt.testdef.TestSuite;
import org.sgt.transformations.ITransformation;

/**
 * This interface describes additional and dedicated methods required
 * to perform a generic transformation of an instance of {@link Graph}
 * (the {@link SourceGraph}) into a {@link TestPlan}.
 * <BR/>
 * {@link AbstractGraph2TestPlanTransformation} implements
 * the generic logic of the transformation and can be used
 * as a staring point for implementations.
 * @author BUTTIGHOFFER-A
 * @see org.sgt.transformations.graph2testdef.AbstractGraph2TestPlanTransformation
 *
 */
public interface IGraph2TestPlanTransformation<SourceGraph extends Graph> extends ITransformation {

	/**
	 * Validates a {@link Graph} for our transformation.
	 * This method is of course dependent of the concrete implementation
	 * of the {@link SourceGraph} chosen for the transformation.
	 * @param graph to validate for transformation.
	 * @return true only if the graph is acceptable as input
	 * for this transformation.
	 */
	public boolean validateSourceGraph(SourceGraph graph);
	
	/**
	 * Computes the different possible {@link Route}s of interest in the
	 * {@link Graph}.
	 * This method is of course dependent of the concrete implementation
	 * of the {@link SourceGraph} chosen for the transformation.
	 * @return the Set of possible {@link Route}s of interest in the {@link Graph}
	 * (may be empty but not null).
	 */
	public Set<Route> computeRoutes();
	
	/**
	 * Initializes a new {@link TesPlan} to receive the result of the transformation.
	 * Implementers should mostly fill the TestPlan's attributes (name, summary ...)
	 * as fitting for their transformation.
	 * This method is of course dependent of the concrete implementation
	 * of the {@link SourceGraph} chosen for the transformation as there should be
	 * a mapping between the Graph's properties and the ones of the TestPlan
	 * object.
	 * @return the initialized {@link TestPlan}.
	 */
	public TestPlan initTestPlan();
	
	/**
	 * Initializes a new {@link TestSuite} to receive test cases
	 * for a given {@link Route}.
	 * Implementers should fill the TestSuite's name attributes
	 * as fitting given the chosen {@link Route}.
	 * @param route the route corresponding to this test suite.
	 * @return the test suite (never null)
	 */
	public TestSuite initTestSuite(final Route route);

	/**
	 * Transforms a {@link Node} into it's associated {@link TesPlan}'s
	 * {@link Step}.
	 * @param node the node to transform.
	 * @return the transformed element ({@link Step}.
	 */
	public Step mappNode(final Node node);
	
	/**
	 * Transforms an ordered sequence of {@link Node}s into
	 * it's associated {@link TestCase}.
	 * @param nodesSeq the sequence to transform.
	 * @param graph2testConditions graph to test conditions map.
	 * @param graph2testConstraints graph to test constraints map.
	 * @return the transformed {@link TestCase}.
	 */
	public TestCase mappNodesSequence(final EList<Node> nodesSeq
			, Map<Condition,TestCondition> graph2testConditions
			, Map<Constraint,TestConstraint> graph2testConstraints
			);

	/**
	 * Getter for input {@link Graph}.
	 * @return the input {@link SourceGraph}
	 */
	public SourceGraph getSourceGraph();

	/**
	 * Getter for output {@link TestPlan}.
	 * @return the output {@link TestPlan}
	 */
	public TestPlan getTestPlan();
	
}
